.TH scf2 5 "5 September 2008" "version 0.91" "Stoker Manual"
.SH NAME
scf2 \- Simple Configuration Format, version 2
.SH DESCRIPTION
SCF2 is a configuration file format that is designed to be powerful, flexible,
and easy to write by hand.
It is NOT designed to be easy to machine-generate, and its import mechanism
is actually quite hostile toward applications that require the ability to
save configuration changes.
.SH COMMENTS, LINE BREAKS, AND ESCAPE SEQUENCES
SCF2 file are line-oriented.
Unlike the original SimpleConfig format, logical lines may span multiple
physical lines by ending the physical line to be continued with a single
backslash (\\) character.
.PP
Comments within SCF2 files are supported in the form of line comments, beginning
with the `#' character.
Insertion of a literal `#' character is possible by using the `\\#' escape
sequence.
Other escape sequences include `\\n', `\\$', and `\\t'.
To insert a literal backslash, use `\\\\'.
.SH EXPRESSIONS
Fundamentally, SCF2 expressions (also called directives) are in the form of
name=value pairs.
Names MAY contain spaces and are otherwise generally free-form.
Thus, the following expressions are valid:

.B some_variable = value

.B some other variable = value
.PP
If a variable name is not yet in the symbol table, then the variable is
added to the symbol table with its value.
Otherwise, the symbol table variable value is replaced with the new value.
Thus, if "some_variable" were set multiple times, only the LAST assignment
would be effective as far as the program is concerned.
.SH CONTROL COMMANDS
All left-hand-side (LHS) expressions must end with the `=' sign, except for
list elements and special constructs.
Two control commands exist in SCF2:
.PP
Other SCF2 files may be imported into the current file with the construct:

.B import filename
.PP
Previously assigned variables (including those imported from other files) may
be removed from the symbol table:

.B unset some_variable
.SH VARIABLE VALUES
If the right-hand-side (RHS) of a standard name = value expression is either
the keyword "true" or the keyword "false" (in any capitalization), then the
value of the variable is stored in the symbol table as a Boolean.
Otherwise, all RHS values are treated as either strings, records, or lists.
.PP
SCF2 files can extract the values of environment variables as seen by the
Python interpreter at the time of program startup.
Environment variables are permitted in RHS strings only, and these have the
form:

.B value_of_home = $HOME$

where the substring between the literal `$' signs is a suitable environment
variable name for getenv(3).
To insert a literal `$' sign into a string, use either `\\$' or `$$'.
.SH LISTS
Lists in SCF2 have the following form, with elements separated by newlines:

.nf
   some_list = [
.nf
   	item1
   	item2
.fi
   ]
.fi

It should be noted that the single ] signifying the end of a list MUST be on
a line by itself.
The first element of a list MAY be on the same line as the opening [.
Anonymous nested lists are ALLOWED:

.nf
   outer_list = [
.nf
   	foo
.nf
   	[  foobar
.nf
   		morefoobar
.fi
   	]
.fi
   	bar
.fi
   ]
.fi
.SH RECORDS
SCF2 records have the form:

.nf
   record_name = {
.nf
   	name = value
   	...
.fi
   }
.fi

A record has exactly the same syntax as the outer SCF2 file itself.
Records may contain any valid SCF2 elements, including lists, nested
sub-records, and import/unset statements.
Each record is also its own namespace: that is, variables set within
a record are local to that record.
In particular, variables set outside a record are NOT defined within the
record construct.
.SH FILE PROCESSING
When an SCF2 file is opened for processing, the file is scanned to produce
tokens used by the recursive-descent parser.
File imports are handled by the scanner, and since these import statements
may occur within a record (and will be limited to the scope of that record),
designing applications that save changes to SCF2 files is not recommended.
.SH GRAMMAR
In the xBNF listing below, literals are shown in
.B bold\c
, while terminals are shown
.I italicized or underlined:
.PP
.nf
S ::= E S
S ::=
E ::= C \fI<string>\fR
C ::= \fBunset\fR \fI<string>\fR
E ::= \fI<string>\fR \fB=\fR R
R ::= \fI<string>\fR
R ::= \fI<boolean>\fR
R ::= \fB[\fR L
R ::= \fB{\fR T
L ::= \fI<string>\fR L
L ::= \fB]\fR
L ::= \fB[\fR G
G ::= L
T ::= N T
T ::= \fB}\fR
N ::= E
.fi
.SH EXAMPLE
Here is an example of a valid SCF2 file:
.PP
.nf
# A syntactically correct (but silly) example
import /opt/something/stuff.sc2
unset foobar
foo = my\\tfair\\tlady
bar = $HOME$/.bar

dollar_home = $$HOME
also_dollar_home = \\$HOME
path_of_home = $HOME$

this name is actually legal! = why?

tasks = [ scrub1
.nf
   scrub2
   scrub3
   scrub4
.fi
]

task_settings = {
.nf
	import /opt/something/task_common.sc2
	task_run_length = 10
	unset task_inhibit    # applies to record scope only!
.fi
}
.fi
.SH SEE ALSO
getenv(3)
.SH AUTHOR
Mike Murphy <mamurph@cs.clemson.edu>
.SH DISCLAIMER
This material is based upon work supported under a National Science
Foundation Graduate Research Fellowship.
Any opinions, findings, conclusions or recommendations expressed in this
publication are those of the author(s) and do not necessarily reflect the
views of the National Science Foundation.
